﻿#region Copyright & License
//
// Project: Quark Framework
// Project site: http://quark.codeplex.com
// See the copyright statement on the project site for more details.
//
// Licensed to the Apache Software Foundation (ASF) under one or more 
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership. 
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with 
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Quark.Framework.Exceptions;

namespace Quark.Framework
{
    /// <summary>
    /// 表示对象实例可配置化的接口
    /// </summary>
    /// <remarks>
    /// <list type=" number">
    /// <listheader>
    /// <term>创建对象实例后，其所实现的接口在容器中被调用顺序依次为：</term>
    /// </listheader>
    /// <item>
    /// <term><see cref="IInitializable.InitializeInstance()"/></term>
    /// <description>初始化对象实例</description>
    /// </item>
    /// <item>
    /// <term><see cref="IContextualizable.Contextualize(IQuarkContext)"/></term>
    /// <description>将对象实例置入上下文环境</description>
    /// </item>
    /// <item>
    /// <term><see cref="IConfigurable.Configure(IConfiguration)"/></term>
    /// <description>初始化对象实例的配置</description>
    /// </item>
    /// <item>
    /// <term><see cref="IStartable.StartRun()"/></term>
    /// <description>启动对象实例</description>
    /// </item>
    /// </list>
    /// </remarks>
    public interface IConfigurable
    {
        /// <summary>
        /// 配置当前对象实例
        /// </summary>
        /// <param name="configuration">当前对象实例的配置数据，传入null空值表示无可用配置</param>
        /// <exception cref="InvokeOnceException">该方法在同一个对象实例上被调用多次引发此异常</exception>
        /// <exception cref="InvalidConfigurationException"><paramref name="configuration"/>配置数据不能被当前对象实例所使用</exception>
        /// <exception cref="ConfigureException">对象实例配置发生异常，内部抛出的异常统一以<see cref="ConfigureException"/>作为异常封装</exception>
        /// <invokeonce/>
        /// <serialization/>
        void Configure(IConfiguration configuration);
    }

    /// <summary>
    /// 本接口是<see cref="IConfigurable"/>接口的泛型版本
    /// </summary>
    /// <typeparam name="TConfiguration">配置类型</typeparam>
    public interface IConfigurable<TConfiguration> : IConfigurable
        where TConfiguration : class, IConfiguration
    {
        /// <summary>
        /// 配置当前对象实例
        /// </summary>
        /// <param name="configuration">当前对象实例的配置数据，传入null空值表示无可用配置</param>
        /// <exception cref="InvokeOnceException">该方法在同一个对象实例上被调用多次引发此异常</exception>
        /// <exception cref="InvalidConfigurationException"><paramref name="configuration"/>配置数据不能被当前对象实例所使用</exception>
        /// <exception cref="ConfigureException">对象实例配置发生异常，内部抛出的异常统一以<see cref="ConfigureException"/>作为异常封装</exception>
        /// <invokeonce/>
        /// <serialization/>
        void Configure(TConfiguration configuration);
    }
}
